---
type: integration
title: '@astrojs/mdx'
description: Aprende como usar la integración @astrojs/mdx en tu proyecto de Astro.
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

Esta **[integración de Astro][astro-integration]** permite el uso de componentes [MDX](https://mdxjs.com/) y te permite crear páginas como archivos `.mdx`.

## ¿Por qué MDX?

MDX te permite [usar variables, expresiones JSX y componentes dentro del contenido Markdown](/es/guides/markdown-content/#características-de-mdx-únicamente) en Astro. Si tienes contenido existente escrito en MDX, esta integración te permite traer esos archivos a tu proyecto de Astro.

## Instalación

Astro incluye un comando `astro add` para automatizar la configuración de las integraciones oficiales. Si lo prefieres, puedes [instalar las integraciones manualmente](#instalación-manual) en su lugar.

Ejecuta uno de los siguientes comandos en una nueva ventana de terminal.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add mdx
  ```
  </Fragment>
 </PackageManagerTabs>

### Instalación Manual

Primero, instala el paquete `@astrojs/mdx`:

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/mdx
  ```
  </Fragment>
</PackageManagerTabs>

Luego, aplica esta integración a tu archivo `astro.config.*` usando la propiedad `integrations`:

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### Integración del Editor

Para soporte en [VS Code](https://code.visualstudio.com/), instala la [extensión oficial de MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx).

Para otros editores, usa el [servidor de lenguaje MDX](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server).

## Uso

Con la integración MDX de Astro, puedes [añadir páginas MDX a tu proyecto](/es/guides/markdown-content/#páginas-de-markdown-y-mdx) añadiendo archivos `.mdx` dentro de tu directorio `src/pages/`. También puedes [importar archivos `.mdx`](/es/guides/markdown-content/#importando-markdown) en archivos `.astro`.

La integración MDX de Astro agrega características adicionales a MDX estándar, incluyendo el frontmatter estilo Markdown. Esto te permite utilizar la mayoría de las características de Markdown incorporadas en Astro, como una [propiedad especial de frontmatter `layout`](/es/guides/markdown-content/#layout-en-el-frontmatter).

Consulta cómo funciona MDX en Astro con ejemplos en nuestra [guía de Markdown y MDX](/es/guides/markdown-content/).

Visita la [documentación de MDX](https://mdxjs.com/docs/what-is-mdx/) para aprender sobre el uso de las características estándar de MDX.

## Configuración

Una vez que la integración MDX esté instalada, no es necesario ninguna configuración adicional para utilizar archivos `.mdx` en tu proyecto Astro.

Puedes configurar cómo se renderiza tu MDX con las siguientes opciones:

* [Opciones heredadas de la configuración de Markdown](#opciones-heredadas-de-la-configuración-de-markdown)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Opciones heredadas de la configuración de Markdown

Todas las opciones de configuración [`markdown`](/es/reference/configuration-reference/#opciones-de-markdown) pueden configurarse por separado en la integración MDX. Esto incluye los plugins remark y rehype, resaltado de sintaxis y más. Las opciones serán por defecto las de tu configuración Markdown ([ver la opción `extendMarkdownConfig`](#extendmarkdownconfig) para modificar esto).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX no admite pasar plugins de remark y rehype como una cadena. En su lugar, debes instalar, importar y aplicar la función del plugin.
:::

<ReadMore>Consulta la [referencia de opciones de Markdown](/es/reference/configuration-reference/#opciones-de-markdown) para ver una lista completa de opciones.</ReadMore>

### `extendMarkdownConfig`

* **Tipo:** `boolean`
* **Por defecto:** `true`

Por defecto, MDX extenderá [la configuración de Markdown existente en tu proyecto](/es/reference/configuration-reference/#opciones-de-markdown). Para anular opciones individuales, puedes especificar su equivalente en la configuración de MDX.

Por ejemplo, digamos que necesitas desactivar el Markdown con formato de GitHub y aplicar un conjunto diferente de plugins de remark para archivos MDX. Puedes aplicar estas opciones de la siguiente manera, con `extendMarkdownConfig` habilitado de forma predeterminada:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // `syntaxHighlight` se hereda de Markdown

      // Markdown `remarkPlugins` ignorados,
      // Solo se aplicó `remarkPlugin2`.
      remarkPlugins: [remarkPlugin2],
      // `gfm` se anuló y se estableció en `false`
      gfm: false,
    }),
  ],
});
```

También es posible que necesites deshabilitar la extensión de configuración `markdown` en MDX. Para ello, establece `extendMarkdownConfig` en `false`:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // La configuración de Markdown ahora se ignora
      extendMarkdownConfig: false,
      // No se aplicaron `remarkPlugins`
    }),
  ],
});
```

### `recmaPlugins`

Estos son plugins que modifican directamente la salida [estree](https://github.com/estree/estree). Esto es útil para modificar o inyectar variables JavaScript en tus archivos MDX.

Sugerimos [utilizar AST Explorer](https://astexplorer.net/) para experimentar con las salidas de estree y probar [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) para buscar entre nodos de JavaScript.

### `optimize`

* **Tipo:** `boolean | { customComponentNames?: string[] }`

Esta es una configuración opcional para optimizar la salida de MDX y acelerar las compilaciones y el renderizado mediante un plugin interno de rehype. Esto puede ser útil si tienes muchos archivos MDX y notas que las compilaciones son lentas. Sin embargo, esta opción puede generar HTML no escapado, por lo que asegúrate de que las partes interactivas de tu sitio sigan funcionando correctamente después de habilitarla.

Esto está desactivado de forma predeterminada. Para habilitar la optimización de MDX, agrega lo siguiente a la configuración de integración de MDX:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### `customComponentNames`

* **Tipo:** `string[]`

Una propiedad opcional de `optimize` para evitar que el optimizador de MDX maneje cualquier [componente personalizado pasado al contenido de MDX importado a través de la prop `components`](/es/guides/markdown-content/#componentes-personalizados-con-mdx-importado).

Deberás excluir estos componentes de la optimización, ya que el optimizador convierte el contenido en una cadena estática de forma anticipada, lo cual romperá los componentes personalizados que necesitan ser renderizados de forma dinámica.

Por ejemplo, la salida de MDX prevista para lo siguiente sería `<Heading>...</Heading>` en lugar de cada `"<h1>...</h1>"`:

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<Content components={{ ...components, h1: Heading }} />
```

Para configurar la optimización de esto utilizando la propiedad `customComponentNames`, especifica un arreglo de nombres de elementos HTML que deben tratarse como componentes personalizados:

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // Evita que el optimizador maneje los elementos `h1`
        // Estos serán tratados como componentes personalizados
        customComponentNames: ['h1'],
      },
    }),
  ],
});
```

Ten en cuenta que si tu archivo MDX [configura componentes personalizados usando `export const components = { ... }`](/es/guides/markdown-content/#asignando-componentes-personalizados-a-elementos-html), entonces no necesitas configurar esta opción manualmente. El optimizador los detectará automáticamente.

## Ejemplos

* La [plantilla de inicio Astro MDX](https://github.com/withastro/astro/tree/latest/examples/with-mdx) muestra cómo utilizar archivos MDX en tu proyecto Astro.

[astro-integration]: /es/guides/integrations-guide/

[astro-ui-frameworks]: /es/guides/framework-components/#usando-componente-de-framework
